<html>
<head><meta charset="utf-8"><title>async vision doc: beginner experience · wg-async-foundations · Zulip Chat Archive</title></head>
<h2>Stream: <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/index.html">wg-async-foundations</a></h2>
<h3>Topic: <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/topic/async.20vision.20doc.3A.20beginner.20experience.html">async vision doc: beginner experience</a></h3>

<hr>

<base href="https://rust-lang.zulipchat.com">

<head><link href="https://rust-lang.github.io/zulip_archive/style.css" rel="stylesheet"></head>

<a name="226050796"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/187312-wg-async-foundations/topic/async%20vision%20doc%3A%20beginner%20experience/near/226050796" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/topic/async.20vision.20doc.3A.20beginner.20experience.html#226050796">(Feb 11 2021 at 20:11)</a>:</h4>
<p>So <span class="user-mention" data-user-id="137147">@Didrik Nordstrom</span> I have a question for you</p>



<a name="226050864"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/187312-wg-async-foundations/topic/async%20vision%20doc%3A%20beginner%20experience/near/226050864" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/topic/async.20vision.20doc.3A.20beginner.20experience.html#226050864">(Feb 11 2021 at 20:12)</a>:</h4>
<p>You may have seen I'm pulling together work on this <a href="https://hackmd.io/p6cmRZ9ZRQ-F1tlhGaN9rg">async vision doc</a>.</p>



<a name="226050885"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/187312-wg-async-foundations/topic/async%20vision%20doc%3A%20beginner%20experience/near/226050885" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/topic/async.20vision.20doc.3A.20beginner.20experience.html#226050885">(Feb 11 2021 at 20:12)</a>:</h4>
<p>I should probably write out what i'm about to type here in the doc</p>



<a name="226050894"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/187312-wg-async-foundations/topic/async%20vision%20doc%3A%20beginner%20experience/near/226050894" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/topic/async.20vision.20doc.3A.20beginner.20experience.html#226050894">(Feb 11 2021 at 20:12)</a>:</h4>
<p>because I've said this like 22 times in the last couple of days</p>



<a name="226050979"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/187312-wg-async-foundations/topic/async%20vision%20doc%3A%20beginner%20experience/near/226050979" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/topic/async.20vision.20doc.3A.20beginner.20experience.html#226050979">(Feb 11 2021 at 20:13)</a>:</h4>
<p>but the basic idea is that it consists of three things:</p>
<ul>
<li>design tenets -- what are the principles we are using to guide us</li>
<li>user stories about how things are now (with a focus on what could be improved, but also the good)</li>
<li>user stories about how we want things to be in the fullness of time (to contrast with how things are today)</li>
</ul>



<a name="226050992"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/187312-wg-async-foundations/topic/async%20vision%20doc%3A%20beginner%20experience/near/226050992" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/topic/async.20vision.20doc.3A.20beginner.20experience.html#226050992">(Feb 11 2021 at 20:13)</a>:</h4>
<p>I expect there to be more there than we can get done in 1 year</p>



<a name="226051007"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/187312-wg-async-foundations/topic/async%20vision%20doc%3A%20beginner%20experience/near/226051007" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/topic/async.20vision.20doc.3A.20beginner.20experience.html#226051007">(Feb 11 2021 at 20:13)</a>:</h4>
<p>but I want it to kind of 'paint a picture' of what we're shooting for</p>



<a name="226051028"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/187312-wg-async-foundations/topic/async%20vision%20doc%3A%20beginner%20experience/near/226051028" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/topic/async.20vision.20doc.3A.20beginner.20experience.html#226051028">(Feb 11 2021 at 20:13)</a>:</h4>
<p>I also was hoping to then kind of use that to assign "owners"</p>



<a name="226051042"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/187312-wg-async-foundations/topic/async%20vision%20doc%3A%20beginner%20experience/near/226051042" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/topic/async.20vision.20doc.3A.20beginner.20experience.html#226051042">(Feb 11 2021 at 20:13)</a>:</h4>
<p>this person is trying to make that thing happen, that sort of thing</p>



<a name="226051111"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/187312-wg-async-foundations/topic/async%20vision%20doc%3A%20beginner%20experience/near/226051111" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/topic/async.20vision.20doc.3A.20beginner.20experience.html#226051111">(Feb 11 2021 at 20:14)</a>:</h4>
<p>I'm curious if you'd be interested in contributing to the doc (or reviewing) around the way you see the book working</p>



<a name="226051130"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/187312-wg-async-foundations/topic/async%20vision%20doc%3A%20beginner%20experience/near/226051130" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/topic/async.20vision.20doc.3A.20beginner.20experience.html#226051130">(Feb 11 2021 at 20:14)</a>:</h4>
<p>I'm going to put in some time to try and make a version that shows more clearly how i see it working ...</p>



<a name="226051137"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/187312-wg-async-foundations/topic/async%20vision%20doc%3A%20beginner%20experience/near/226051137" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/topic/async.20vision.20doc.3A.20beginner.20experience.html#226051137">(Feb 11 2021 at 20:14)</a>:</h4>
<p>(also this goes for others who might have interest in contributing to the effort)</p>



<a name="226053126"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/187312-wg-async-foundations/topic/async%20vision%20doc%3A%20beginner%20experience/near/226053126" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Didrik Nordstrom <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/topic/async.20vision.20doc.3A.20beginner.20experience.html#226053126">(Feb 11 2021 at 20:30)</a>:</h4>
<p>Yeah, I'd be delighted to. Do you want a section on the vision for the book? And which communication channels are we using for the conversations?</p>



<a name="226053331"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/187312-wg-async-foundations/topic/async%20vision%20doc%3A%20beginner%20experience/near/226053331" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/topic/async.20vision.20doc.3A.20beginner.20experience.html#226053331">(Feb 11 2021 at 20:31)</a>:</h4>
<p>have you put thought into what <code>async</code> looks like for library authors? like on guides for transitioning from sync to async code?</p>



<a name="226412037"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/187312-wg-async-foundations/topic/async%20vision%20doc%3A%20beginner%20experience/near/226412037" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/topic/async.20vision.20doc.3A.20beginner.20experience.html#226412037">(Feb 15 2021 at 17:37)</a>:</h4>
<p><span class="user-mention" data-user-id="137147">@Didrik Nordstrom</span> I do =)</p>



<a name="226412074"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/187312-wg-async-foundations/topic/async%20vision%20doc%3A%20beginner%20experience/near/226412074" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/topic/async.20vision.20doc.3A.20beginner.20experience.html#226412074">(Feb 15 2021 at 17:37)</a>:</h4>
<p>but as I was working over the weekend I realized something</p>



<a name="226412088"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/187312-wg-async-foundations/topic/async%20vision%20doc%3A%20beginner%20experience/near/226412088" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/topic/async.20vision.20doc.3A.20beginner.20experience.html#226412088">(Feb 15 2021 at 17:38)</a>:</h4>
<p>which you will see reflected in <a class="stream-topic" data-stream-id="187312" href="/#narrow/stream/187312-wg-async-foundations/topic/async.20vision">#wg-async-foundations &gt; async vision</a></p>



<a name="226412144"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/187312-wg-async-foundations/topic/async%20vision%20doc%3A%20beginner%20experience/near/226412144" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/topic/async.20vision.20doc.3A.20beginner.20experience.html#226412144">(Feb 15 2021 at 17:38)</a>:</h4>
<p>in particular, when I think about what i'd like to see <strong>in the fullness of time</strong>, I don't know how much of a role there is for an "async book'</p>



<a name="226412171"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/187312-wg-async-foundations/topic/async%20vision%20doc%3A%20beginner%20experience/near/226412171" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/topic/async.20vision.20doc.3A.20beginner.20experience.html#226412171">(Feb 15 2021 at 17:38)</a>:</h4>
<p>I imagine that this stuff would be integrated into our standard materials</p>



<a name="226412490"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/187312-wg-async-foundations/topic/async%20vision%20doc%3A%20beginner%20experience/near/226412490" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/topic/async.20vision.20doc.3A.20beginner.20experience.html#226412490">(Feb 15 2021 at 17:41)</a>:</h4>
<p>that said</p>



<a name="226412496"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/187312-wg-async-foundations/topic/async%20vision%20doc%3A%20beginner%20experience/near/226412496" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/topic/async.20vision.20doc.3A.20beginner.20experience.html#226412496">(Feb 15 2021 at 17:41)</a>:</h4>
<p>I think in the <em>short term</em> we totally want an async book</p>



<a name="226412509"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/187312-wg-async-foundations/topic/async%20vision%20doc%3A%20beginner%20experience/near/226412509" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/topic/async.20vision.20doc.3A.20beginner.20experience.html#226412509">(Feb 15 2021 at 17:41)</a>:</h4>
<p>i imagined this showing up in the (yet to be written...) roadmap section</p>



<a name="226412528"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/187312-wg-async-foundations/topic/async%20vision%20doc%3A%20beginner%20experience/near/226412528" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/topic/async.20vision.20doc.3A.20beginner.20experience.html#226412528">(Feb 15 2021 at 17:41)</a>:</h4>
<p><span class="user-mention silent" data-user-id="232545">Joshua Nelson</span> <a href="#narrow/stream/187312-wg-async-foundations/topic/async.20vision.20doc.3A.20beginner.20experience/near/226053331">said</a>:</p>
<blockquote>
<p>have you put thought into what <code>async</code> looks like for library authors? like on guides for transitioning from sync to async code?</p>
</blockquote>
<p>say more :) I think that'd be a great thing to be thinking about!</p>



<a name="226419574"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/187312-wg-async-foundations/topic/async%20vision%20doc%3A%20beginner%20experience/near/226419574" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/topic/async.20vision.20doc.3A.20beginner.20experience.html#226419574">(Feb 15 2021 at 18:59)</a>:</h4>
<p><span class="user-mention silent" data-user-id="116009">nikomatsakis</span> <a href="#narrow/stream/187312-wg-async-foundations/topic/async.20vision.20doc.3A.20beginner.20experience/near/226412528">said</a>:</p>
<blockquote>
<p><span class="user-mention silent" data-user-id="232545">Joshua Nelson</span> <a href="#narrow/stream/187312-wg-async-foundations/topic/async.20vision.20doc.3A.20beginner.20experience/near/226053331">said</a>:</p>
<blockquote>
<p>have you put thought into what <code>async</code> looks like for library authors? like on guides for transitioning from sync to async code?</p>
</blockquote>
<p>say more :) I think that'd be a great thing to be thinking about!</p>
</blockquote>
<p>I realize now that I haven't actually tried to do this for <em>libraries</em>, that's not really what I'm asking (although I am slightly concerned by the "what color is your function" issue where libraries have to have both sync and async interfaces, like <code>reqwest::blocking</code>, but I'm sure you've already thought about that).</p>
<p>My main concern is I've been hesitant in the past to migrate <a href="http://docs.rs">docs.rs</a> to async because I don't feel confident that the semantic behavior is the same before and after. There's a very long thread about this here: <a href="https://github.com/rust-lang/docs.rs/pull/915">https://github.com/rust-lang/docs.rs/pull/915</a> but the main concerns I have are:</p>
<ol>
<li>How does <code>async</code> interact with panics and <code>catch_unwind</code>?</li>
<li>How can I get a useful mental model of the code? When reading async code I have a lot of questions like <a href="https://github.com/rust-lang/docs.rs/pull/910#discussion_r460446221">https://github.com/rust-lang/docs.rs/pull/910#discussion_r460446221</a> where I just don't understand the runtime semantics of the code. The problem is not getting it to compile, the problem is that I don't know how to predict the behavior, especially the performance implications. Since <code>async</code> in my mind is mostly about performance, that seems like a pretty big issue.</li>
<li>Translating sync code to async is a lot of work and also pretty menial; mostly it's just adding <code>async</code> and <code>await</code> keywords in lots of places. <a href="https://github.com/jyn514/docs.rs/tree/sqlx">I spent quite a while on this</a> without feeling like I accomplished much.</li>
</ol>
<p>I think 1. is mostly a property of the executor and I should ask <code>tokio</code> about it. For 3.  I don't know if Rust can help here from a language perspective, I think <a href="http://docs.rs">docs.rs</a> just has lots of code. FWIW I get the same feeling about <a href="https://github.com/rust-lang/rust/pull/82020">translating things from interior to exterior mutability</a>, so this isn't unique to async. I think 2. could definitely be helped by more and better documentation though.</p>



<a name="226420037"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/187312-wg-async-foundations/topic/async%20vision%20doc%3A%20beginner%20experience/near/226420037" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/topic/async.20vision.20doc.3A.20beginner.20experience.html#226420037">(Feb 15 2021 at 19:04)</a>:</h4>
<p>Anyway, that's my perspective as someone who's used a lot of rust but not a lot of async. Maybe the moral here is I should use async in small projects before trying to use it in big ones.</p>



<a name="226423036"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/187312-wg-async-foundations/topic/async%20vision%20doc%3A%20beginner%20experience/near/226423036" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/topic/async.20vision.20doc.3A.20beginner.20experience.html#226423036">(Feb 15 2021 at 19:37)</a>:</h4>
<ol>
<li>doesn't really have much to do with executor-- well, at least it doesn't until you start spawning things</li>
</ol>



<hr><p>Last updated: Aug 07 2021 at 22:04 UTC</p>
</html>